Using the long-press manipulator

Use the long-press manipulator to enable users to long-press nodes in your Kanzi application. This way you can make the application react when the user presses and holds the pointer pressed on a node for the amount of time you set in the long-press manipulator. For example, use the long-press manipulator to open a context menu. See Enabling the long-press gesture for a node.

Use the Long Press trigger to react to the long-press gesture. For example, you can change the appearance of a node when the user presses that node. See Using the Long Press trigger.

The long-press manipulator is one of the input manipulators you can use to add gesture recognition to nodes in your Kanzi application. You can assign the input manipulators through the Kanzi Engine API. See Using input manipulators.

Learn how to use the long-press manipulator by completing a tutorial. See Tutorial: Pan, zoom, tap.

Enabling the long-press gesture for a node

This section explains how you can enable the long-press gesture for any node. To enable long press for a Button node, see Using Button triggers.

To enable the long-press gesture for a node:

In Kanzi Studio create a project using the Application template.
In the Project create a node for which you want to enable the long-press gesture.
For example, create an Empty Node 2D node, name it LongPressNode, and add content to the node.
In the Project select the node you created in the previous step, in the Properties add the Hit Testable property, and set it to enabled.
When you enable this property you enable the user to pick a node.
By default hit testing is enabled for the Button, List Box Item Container, Scroll View, and Slider nodes. See Defining which node receives user input.
In the Project press Alt and right-click the node you created and select Alias.
Kanzi Studio creates an alias pointing to the node from which you created the alias and adds it to the resource dictionary of its nearest ancestor node that contains a resource dictionary.
Access alias target nodes using the # sign followed by the name of the alias.
Select File > Export > Export KZB.
Kanzi Studio creates the kzb file and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in the <ProjectName>/Application/bin directory or the location you specify in the Binary Export Directory property in Project > Properties. The kzb file contains all nodes and resources from your Kanzi Studio project, except the resources you mark in a localization table as locale packs.
When you run your Kanzi application from Visual Studio, your application loads the kzb file and configuration files.

In Visual Studio open the solution stored in <ProjectName>/Application/configs/platforms/win32 and in the file which implements the logic of your application create and configure the long-press manipulator:

Define the handler for the LongPressManipulator::LongPressMessage message.
For example, after the public section of the class which implements the logic of your application add:

private:

    // Define the handler for the LongPressManipulator::LongPressMessage message from the nodes 
    // that have an input manipulator which generates the long-press message.
    void onLongPress(LongPressManipulator::LongPressMessageArguments& messageArguments)
    {
        // Add the code that handles the long-press event.
    }

In the onProjectLoaded() function create a LongPressManipulator manipulator and subscribe to its message.
For example, add:

    virtual void onProjectLoaded() KZ_OVERRIDE
    {
        ScreenSharedPtr screen = getScreen();
        Domain* domain = getDomain();

        // Get the LongPressNode node using its alias.
        NodeSharedPtr longPressNode = screen->lookupNode<Node>("#LongPressNode");

        // Create an input manipulator that generates the long-press message.
        LongPressManipulatorSharedPtr longPressManipulator = LongPressManipulator::create(domain);

        // Add the input manipulator to the LongPressNode node.
        longPressNode->addInputManipulator(longPressManipulator);

        // Set the duration of the long press to 250 ms. The default duration is 500 ms.
        // The long press manipulator recognizes the gesture when the user presses the node
        // for this amount of time.
        longPressManipulator->setPressDuration(chrono::milliseconds(250));

        // Subscribe to the LongPressManipulator::LongPressMessage message at the LongPressNode node.
        // The LongPressManipulator manipulator generates this message when the user presses the node
        // for the amount of milliseconds you set with the LongPressManipulator::setPressDuration function.
        longPressNode->addMessageHandler(LongPressManipulator::LongPressMessage, bind(&MyProject::onLongPress, this, placeholders::_1));
    }

Build and run your application. See Deploying Kanzi applications.
In the application press the node for which you enabled the long-press gesture. The application executes the behavior you defined in the handler for the LongPressMessage message.

Using the Long Press trigger

Use the Long Press trigger to react to the long-press gesture. For example, you can change the appearance of a node when the user presses that node.

To use the Long Press trigger:

Enable the long-press gesture for a node. See Enabling the long-press gesture for a node.
Define the behavior that you want to set with the Long Press trigger.
For example, create a state manager where you define the states which set the appearance of a node when the Long Press trigger is set off repeatedly. See Creating a state manager.
In the Project select the node to which you want to add the trigger, and in the Node Components > Triggers section add the Long Press trigger.
In the trigger you created in the previous step click Trigger Settings and in the Trigger Settings Editor disable the Set Message Handled property.
When you disable the Set Message Handled property, this trigger intercepts the message, but does not stop it. This way you let the input manipulator handle the message.
In the trigger you created, in the Add dropdown menu select an action and configure it.
For example, select the Next State action, and in the action settings set:
- Target Item to the node which uses the state manager you created to set the appearance of a node when the Long Press trigger is set off repeatedly
- State Group to the state group which contains the states between which you want to switch when the Long Press trigger is set off
Select File > Export > Export KZB.
Build and run your application. See Deploying Kanzi applications.
In the application press the node for which you enabled the long-press gesture.